/*
 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang;
import java.util.*;

/**
 * 此接口对实现它的每个类的对象强加全序排序。这种排序被称为类的<i>自然排序</i>，
 * 类的 <tt>compareTo</tt> 方法被称为其<i>自然比较方法</i>。<p>
 *
 * 实现此接口的对象列表（和数组）可以通过 {@link Collections#sort(List) Collections.sort}
 * （和 {@link Arrays#sort(Object[]) Arrays.sort}）自动排序。实现此接口的对象可以用作
 * {@linkplain SortedMap 有序映射}中的键或 {@linkplain SortedSet 有序集合}中的元素，
 * 而无需指定 {@linkplain Comparator 比较器}。<p>
 *
 * 当且仅当对于类 <tt>C</tt> 的每个 <tt>e1</tt> 和 <tt>e2</tt>，
 * <tt>e1.compareTo(e2) == 0</tt> 与 <tt>e1.equals(e2)</tt> 具有相同的布尔值时，
 * 类 <tt>C</tt> 的自然排序被称为<i>与 equals 一致</i>。请注意，<tt>null</tt>
 * 不是任何类的实例，即使 <tt>e.equals(null)</tt> 返回 <tt>false</tt>，
 * <tt>e.compareTo(null)</tt> 也应该抛出 <tt>NullPointerException</tt>。<p>
 *
 * 强烈建议（但不是必需的）自然排序与 equals 一致。这是因为没有显式比较器的有序集合
 * （和有序映射）在与自然排序与 equals 不一致的元素（或键）一起使用时会表现得"奇怪"。
 * 特别是，这样的有序集合（或有序映射）违反了集合（或映射）的一般约定，
 * 该约定是根据 <tt>equals</tt> 方法定义的。<p>
 *
 * 例如，如果向不使用显式比较器的有序集合中添加两个键 <tt>a</tt> 和 <tt>b</tt>，
 * 使得 {@code (!a.equals(b) && a.compareTo(b) == 0)}，则第二个 <tt>add</tt>
 * 操作返回 false（并且有序集合的大小不会增加），因为从有序集合的角度来看，
 * <tt>a</tt> 和 <tt>b</tt> 是等价的。<p>
 *
 * 几乎所有实现 <tt>Comparable</tt> 的 Java 核心类都具有与 equals 一致的自然排序。
 * 一个例外是 <tt>java.math.BigDecimal</tt>，其自然排序将具有相等值和不同精度的
 * <tt>BigDecimal</tt> 对象视为相等（例如 4.0 和 4.00）。<p>
 *
 * 对于数学倾向的人，定义给定类 C 上自然排序的<i>关系</i>是：<pre>
 *       {(x, y) such that x.compareTo(y) &lt;= 0}.
 * </pre> 此全序的<i>商</i>是：<pre>
 *       {(x, y) such that x.compareTo(y) == 0}.
 * </pre>
 *
 * 从 <tt>compareTo</tt> 的约定可以立即得出，商是 <tt>C</tt> 上的<i>等价关系</i>，
 * 自然排序是 <tt>C</tt> 上的<i>全序</i>。当我们说类的自然排序<i>与 equals 一致</i>时，
 * 我们的意思是自然排序的商是由类的 {@link Object#equals(Object) equals(Object)} 方法定义的等价关系：<pre>
 *     {(x, y) such that x.equals(y)}. </pre><p>
 *
 * 此接口是
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 * Java 集合框架</a>的成员。
 *
 * @param <T> 此对象可以与之比较的对象类型
 *
 * @author  Josh Bloch
 * @see java.util.Comparator
 * @since 1.2
 */
public interface Comparable<T> {
    /**
     * 将此对象与指定对象进行比较以确定顺序。根据此对象小于、等于或大于指定对象，
     * 返回负整数、零或正整数。
     *
     * <p>实现者必须确保对于所有 <tt>x</tt> 和 <tt>y</tt>，
     * <tt>sgn(x.compareTo(y)) == -sgn(y.compareTo(x))</tt>。
     * （这意味着当且仅当 <tt>y.compareTo(x)</tt> 抛出异常时，
     * <tt>x.compareTo(y)</tt> 必须抛出异常。）
     *
     * <p>实现者还必须确保关系是传递的：
     * <tt>(x.compareTo(y)&gt;0 &amp;&amp; y.compareTo(z)&gt;0)</tt> 意味着
     * <tt>x.compareTo(z)&gt;0</tt>。
     *
     * <p>最后，实现者必须确保 <tt>x.compareTo(y)==0</tt> 意味着对于所有 <tt>z</tt>，
     * <tt>sgn(x.compareTo(z)) == sgn(y.compareTo(z))</tt>。
     *
     * <p>强烈建议（但<i>不是</i>严格要求）<tt>(x.compareTo(y)==0) == (x.equals(y))</tt>。
     * 一般来说，任何实现 <tt>Comparable</tt> 接口并违反此条件的类都应该清楚地说明这一事实。
     * 推荐的语言是"注意：此类具有与 equals 不一致的自然排序。"
     *
     * <p>在上述描述中，符号 <tt>sgn(</tt><i>expression</i><tt>)</tt> 表示数学
     * <i>符号</i>函数，该函数根据 <i>expression</i> 的值是负数、零还是正数，
     * 定义为返回 <tt>-1</tt>、<tt>0</tt> 或 <tt>1</tt> 中的一个。
     *
     * @param   o 要比较的对象。
     * @return  根据此对象小于、等于或大于指定对象，返回负整数、零或正整数。
     *
     * @throws NullPointerException 如果指定对象为 null
     * @throws ClassCastException 如果指定对象的类型阻止它与此对象进行比较。
     */
    public int compareTo(T o);
}
